home *** CD-ROM | disk | FTP | other *** search
/ EuroCD 3 / EuroCD 3.iso / Programming / BlitzBasic / CIATrkrLib / Docs / CIATrackerLibrary.doc next >
Text File  |  1998-06-24  |  15KB  |  487 lines
  1. VER: 1.0
  2. author "Crossbones"
  3. (c) "1995 Binary Assault"
  4.  
  5.  
  6.  
  7.                           CIA Protracker Library
  8.                               Blitz Basic II
  9.  
  10.                          Version 1.02b (14/11/95)
  11.  
  12.                                 Updated by:
  13.                          Crossbones/Binary Assault
  14.  
  15. Introduction:
  16. ~~~~~~~~~~~~~
  17. The standard soundtracker replay routines supplied with Blitz Basic 2 have
  18. many faults, which this library attempts to overcome.  Some of the features
  19. are:
  20.  
  21.   - Plays all PT songs that utilise either the VBLANK timing or the
  22.     more recent CIA based timings
  23.   - Plays back correctly on 50/60Hz systems, running either PAL or NTSC
  24.   - Contains more specialised functions for advanced programmers
  25.   - Enables the programmer to syncronise graphics with their music
  26.  
  27.  
  28. Credits:
  29.  
  30. Original ProTracker playroutine by Amiga Freelancers, converted and enhanced
  31. for Blitz by Neil O'Rourke.  Naggings from Roy, Jeff and Richard. Newer
  32. revisions and further enhancements by Crossbones/Binary Assault.
  33.  
  34.  
  35. NOTE:
  36.  
  37.  Neil stopped work on the library at version 1.6. Unfortunately, all the
  38. source code I've located of this library is only at version 1.3. This means
  39. that if you are fimiliar with the last version of his library, a few of the
  40. commands might not contain the same sytax or might not even be in this library
  41. any more.
  42.  
  43.  If you find that you simply can't live without a certain feature, you might
  44. try to contact me and coax me into providing the update you need.  I say
  45. *MIGHT* because there is no guarentee that I'll work on it.
  46.  
  47.  
  48.  
  49. Getting Started:
  50. ~~~~~~~~~~~~~~~~
  51. What you'll need:
  52.  
  53.  o Blitz Basic II version 1.8 or greater.
  54.  o An Amiga*
  55.  o Any music file in protracker format.
  56.  
  57.  
  58. Machine Requirements:
  59.  
  60.  o Kickstart 2.0x+
  61.  o At least 1 meg of chip ram.
  62.  o A kickin' stereo.
  63.  
  64.  
  65. Installing the library:
  66.  
  67.  First, remove any older version of this library you might have. Look for
  68. names such as "NeilsTrackerLib.obj" or "CiaTrackerLib.obj." Don't delete them,
  69. but move them out of the way for now, keeping them until you're sure you don't
  70. need them, or that you've found the correct library to remove.
  71.  
  72.  Now copy the included library into your blitzlibs:userlibs directory. Once
  73. copied, you'll need to recompile your DEFLIBS file to use it. (NOTE: Users of
  74. version 2.1 need not do this, according to Acid.)
  75.  
  76. * - I sincerely hope you have one of these. :)
  77.  
  78.  
  79.  
  80. List of Commands:
  81. ~~~~~~~~~~~~~~~~~
  82.                              LoadTrackerModule 
  83.                                StartTracker    
  84.                                 StopTracker    
  85.                                DecodeModule    
  86.                               GetTrackerSize   
  87.                             GetTrackerLocation 
  88.                              FreeTrackerModule 
  89.                               GetTrackerEvent  
  90.                              CheckTrackerEvent 
  91.                              WaitTrackerEvent  
  92.                               CheckTrackerID   
  93.                                ModuleToChip    
  94.                               GetModuleName$   
  95.                             ModulePositionJump 
  96.                              GetModulePosition 
  97.                                 PauseModule    
  98.                             ChangeTrackerVBLank
  99.                                 PlayTracker    
  100.                                TrackerVolume   
  101.                              ChangeTrackerMask 
  102.                                ModulePatterns  
  103.  
  104.  
  105. The Commands (Explained):
  106. ~~~~~~~~~~~~~~~~~~~~~~~~~
  107.                              LoadTrackerModule
  108.  
  109. Usage:
  110.  
  111. success=LoadTrackerModule(TrackerModule#,FileName$)
  112.  
  113. Comments:
  114.  
  115. Loads the named module into chip ram, ready for playing.  This command can
  116. only be called in Amiga mode.  success is a boolean return code (true).  If
  117. the load fails for any reason, success returns the AmigaDOS error code.
  118.  
  119. Note that there is an implicit call to FreeTrackerModule for whatever module
  120. you are trying to load.  However, if you want to load another module, don't
  121. try to load it on top of the existing one that is playing. Use another
  122. TrackerModule# (you have from 0 to 8).  The results are unpredictable, and
  123. range from nothing to a system crash.  We can't call StopTracker, because this
  124. will stop everything.
  125.  
  126.                                StartTracker
  127.  
  128. Usage:
  129.  
  130. success=StartTracker(TrackerModule#)
  131.  
  132. Comments:
  133.  
  134. Starts to play the requested module, stopping any modules already playing, or
  135. restarts the current module, and returns true.  Returns false if the module
  136. couldn't be started for some reason (like it isn't loaded).
  137.  
  138.                                 StopTracker
  139.  
  140. Usage:
  141.  
  142. StopTracker
  143.  
  144. Comments:
  145.  
  146. Stops the current module. Not much to it, really.
  147.  
  148.                                DecodeModule
  149.  
  150. Usage:
  151.  
  152. DecodeModule TrackerModule#,ModuleAddress
  153.  
  154. Comments:
  155.  
  156.  This sets an arbitary area of memory as a tracker module, useful if you have
  157. BLoaded/INCBIN'd a file and want to hear if it is a module. Caution:  a
  158. non-module may crash the Amiga when you try to play it.
  159.  
  160. NOTE: As of release 1.02a, the ModuleToChip command has been changed.
  161.       DecodeModule now does this for you automatically if the module that
  162.       is being decoded is in fast ram. The ModuleToChip command will still
  163.       tokenise though, to prevent problems that might occur to previous
  164.       users of this library.
  165.  
  166.                               GetTrackerSize
  167.  
  168. Usage:
  169.  
  170. trackerlength=GetTrackerSize(TrackerModule#)  
  171.  
  172. Comments:
  173.  
  174. Not really much of a useful command. Simply returns the size (in bytes) that
  175. the module is using in memory. There should be no need to use this
  176. information,  and these commands are only included because they served a
  177. purpose in debugging  a long time ago, and to remove them would cause problems
  178. with the Blitz tokens.
  179.  
  180.                               GetTrackerLocation
  181.  
  182. Usage:
  183.  
  184. trackerlength=GetTrackerLocation(TrackerModule#)  
  185.  
  186. Comments:
  187.  
  188. Not really much of a useful command. Simply returns the memory location that
  189. the module is occupying. There should be no need to use this information,  and
  190. these commands are only included because they served a purpose in debugging  a
  191. long time ago, and to remove them would cause problems with the Blitz tokens.
  192.  
  193.                              FreeTrackerModule
  194.  
  195. Usage:
  196.  
  197. FreeTrackerModule TrackerModule#
  198.  
  199. Comments:
  200.  
  201. This frees a module loaded with LoadTrackerModule.  You cannot free a module
  202. that has been set up with DecodeModule (see below), but there is nothing to
  203. stop you trying.
  204.  
  205.                               GetTrackerEvent
  206.  
  207. Usage:
  208.  
  209. trackerevent=GetTrackerEvent
  210.  
  211. Comments:
  212.  
  213. This command is a customised extension to the ProTracker replay routine.  A
  214. "TrackerEvent" occurs when the replay routine comes across a $8xx command.
  215. This command is not defined in the command list, and many demos (eg Jesus on
  216. E's) use it to trigger effects.  This command gets the most recent
  217. TrackerEvent, so any program looking at this will have to compare the current
  218. value to the value that triggered the current effect.
  219.  
  220.                              CheckTrackerEvent
  221.  
  222. Usage:
  223.  
  224. success=CheckTrackerEvent
  225.  
  226. Comments:
  227.  
  228. This routine checks to see if a TrackerEvent has occured since the last time
  229. the routine was called, and returns True if it has.  Use GetTrackerEvent to
  230. determine what data the $8xx command had.
  231.  
  232.                              WaitTrackerEvent
  233.  
  234. Usage:
  235.  
  236. Unknown
  237.  
  238. Comments:
  239.  
  240. ** V1.6: DO NOT USE THIS COMMAND! **
  241.  
  242. ** V1.0b: I haven't checked this. **
  243.  
  244.                                CheckTrackerID
  245.  
  246. Usage:
  247.  
  248. success=CheckTrackerID(TrackerModule#)
  249.  
  250. Comments:
  251.  
  252. This checks the module for the standard Pro/Noise/SoundTracker ID string
  253. "M.K." (or "M!K!" in the case of a 100 pattern PT module), and returns True if
  254. one of them is found.  This means that you can safely call StartTracker.
  255.  
  256. Note that there is no 100% guarenteed way of determining what is a module and
  257. what isn't.  Bit Arts, for example, remove the M.K. identifier to make it
  258. harder to rip modules, so if you're writing a module ripping program, you have
  259. to take this result with a grain of salt.
  260.  
  261.                                ModuleToChip
  262.  
  263.  
  264.  
  265. NOTE: This command is outdated as of this release. Even though the command
  266.       will tokenise, the command has no function. Please see the
  267.       DecodeModule command for more details.
  268.  
  269.                               GetModuleName$
  270.  
  271. Usage:
  272.  
  273. name$=GetModuleName$(TrackerModule#)
  274.  
  275. Comments:
  276.  
  277. Returns the name of the module in name$. Not too useful, but I made a little
  278. interface for workbench using the library, and needed a command like this.
  279.  
  280.                             ModulePositionJump
  281.  
  282. Usage:
  283.  
  284. ModulePositionJump(Position#)
  285.  
  286. Comments:
  287.  
  288.  This command tells the play routine to jump to the pattern requested in
  289. Position#.
  290.  
  291. NOTE: There is no error checking done at this time. It would be wise to know
  292.       where you're going.
  293.  
  294.                              GetModulePosition
  295.  
  296. Usage:
  297.  
  298. position=GetModulePosition
  299.  
  300. Comments:
  301.  
  302. This returns the current pattern the replay routine is playing.
  303.  
  304.                                 PauseModule
  305.  
  306. Usage:
  307.  
  308. PauseModule
  309.  
  310. Comments:
  311.  
  312. Stops the current module from playing, effectively pausing it. Use the command
  313. again to unpause it.
  314.  
  315.                             ChangeTrackerVBlank
  316.  
  317. Usage:
  318.  
  319. ChangeTrackerVBlank
  320.  
  321. Comments:
  322.  
  323. This command seems pretty useless, but there sure are alot of module players
  324. that offer vblank timing. Call the command before playing the module, then
  325. call the StartTracker command, so it knows which module to use. Then simply
  326. call the PlayModule command on every vblank.
  327.  
  328.                                 PlayModule
  329.  
  330. Usage:
  331.  
  332. PlayModule
  333.  
  334. Comments:
  335.  
  336.  This command is to be used if you use the ChangeTrackerVBlank command.
  337.  
  338.  To use this command, call ChangeTrackerVBlank first. Secondly, call the
  339. StartTracker command. At each vblank, you must then call PlayMoudule, which
  340. will keep the music playing.
  341.  
  342.                                TrackerVolume
  343.  
  344. Usage:
  345.  
  346. TrackerVolume [Volume Level]
  347.  
  348. Comments:
  349.  
  350.  What can be said? This command changes the volume level of the module. Note:
  351. this effects all the channels currently masked in. (Refer to the command
  352. ChangeTrackerMask for more information on this).
  353.  
  354.                              ChangeTrackerMask
  355.  
  356. Usage:
  357.  
  358. ChangeTrackerMask [NewMask]
  359.  
  360. Comments:
  361.  
  362.  For all intents and purposes, you might never need this command. This command
  363. allows you to tell the replay routine that it is not supposed to use a certain
  364. channel, or certain channels. This is useful if you want, for instance, a two
  365. channel module playing and sounds effects at the same time. The command wants
  366. to know what channels the replay routine CAN use.
  367.  
  368. How to figure out what channels to mask:
  369.  
  370.  This is fairly simple, and there are a couple of different ways to do this.
  371.  
  372.  1. ChangeTrackerMask %0000ABCD - Where ABCD represents channels 0-3.
  373.  
  374.     Channels to be used by the replay routine would be represented as
  375.     1's, and channels you wish to use for sound effects, etc., would be
  376.     represented as 0's.
  377.  
  378.     Example: ChangeTrackerMask %00001001 would play channels 0 and 3, while
  379.     channels 1 and 2 would be free for you to use.
  380.  
  381.  2. ChangeTrackerMask [DecimalValue] - Where decimal value represents:
  382.  
  383.     1 - Channel 0
  384.     2 - Channel 1
  385.     4 - Channel 2
  386.     8 - Channel 3
  387.  
  388.     Example: ChangeTrackerMask 9 would play channels 0 and 3, while channels
  389.     1 and 2 would be free for you to use.
  390.  
  391.                               ModulePatterns
  392.  
  393. Usage:
  394.  
  395. patt=ModulePatterns(Module#)
  396.  
  397. Comments:
  398.  
  399.  This command is kind of useless, but I wanted one so it's included. ;) All
  400. this command does is return the number of patterns used in the module.
  401.  
  402.  
  403.  
  404. Revision History:
  405. ~~~~~~~~~~~~~~~~~
  406. Pre 1.01B:
  407.  
  408.  -Original version by Neil updated to use a decent method of CIA timing. No
  409.   longer needs the crappy "SetDMA" command. :)
  410.  
  411. 1.01B:
  412.  
  413.  -Fixed problem with slots. (Was supposed to be able to allow 0-8, but was
  414.   only set only to keep track through 7.
  415.  -Added various commands in an attempt to get up to date with the commands
  416.   from Neil's last update. (Version 1.6)
  417.  -Added better run-time error checking (Limited edition version of 1.01B.)
  418.  
  419. 1.02 (Current):
  420.  
  421.  -Hoo boy! Did I ever screw up 1.01B. Good thing I didn't send it too much.
  422.   Seems that the run-time errors section REALLY made a mess of things.
  423.   Deleted them and rewrote the entire error checking system. MUCH better.
  424.  -I am now using the TrackerTester program on all versions of the library
  425.   ready for release. Since I have problems with beta testers offering to
  426.   help, then never saying a damn thing once they get the library, I figure
  427.   this is the next best thing. Checks all major commands for failure.
  428.   (NOTE: This program is now included in releases. Use it if you have
  429.   problems and report the errors/bugs to me for fixing.)
  430.  -Fixed small problem with LoadTrackerModule command. (1.02a)
  431.  -DecodeModule command changed to also include function from ModuleToChip.
  432.   ModuleToChip still tokenises, but performs no function. (1.02a)
  433.  -Repaired section that grabs the cia timer. This fixed the following
  434.   problems:
  435.   - Used to lose characters over the serial port when the player was active.
  436.   - Failed to play if one of the two cia timers was being used. (It only
  437.     was able to allocate one timer successfully, and failed on the other.)
  438.   These two should fix any problems the player had on specific machines.
  439.   (1.02a)
  440.  
  441.  
  442.  
  443. Bugs:
  444. ~~~~~
  445. Things I know about
  446.  
  447.  o Because of some unknown problem, the routine actually reserves 3 bytes of
  448.    memory (added to the actual module size.) Keep this in mind when calling
  449.    the function to find out the byte-size of a module.
  450.  
  451. Things I don't know about
  452.  
  453.  Well!?! If I don't know about them, I can't really put them here can I? ;)
  454.  
  455.                         How to Contact the Author:
  456.                             (This part's easy!)
  457.  
  458.                          Crossbones/Binary Assault
  459.                               aka Steve Flock
  460.  
  461.                                Via Internet
  462.                            sflock@comtch.iea.com
  463.  
  464.                               Via Snail-Mail
  465.                                 Steve Flock
  466.                             2421 west LaCrosse
  467.                             Spokane, Washington
  468.                                    99205
  469.  
  470. (Note: Please be sure that if you're contacting me via snailmail that you put
  471. the correct postage on the letter. If I have to pay to get the mail, chances
  472. are you won't get a reply.)
  473.  
  474.  
  475.  
  476.  
  477. People who have helped and deserve to be mentioned:
  478. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  479.  
  480.                              Ted Bailey
  481.                           Andrew (Defender)
  482.                            Richard Elmore
  483.  
  484.  
  485.  I know there are more, but I've forgotten your names. If you're seeing this
  486. and saying "Geez, and he forgot me!" then get ahold of me and let me know.
  487.